Ana içeriğe geç

Webhook'lar

Bu belge TrustChex sistemindeki webhook işlevselliğini açıklamaktadır.

Genel Bakış​

Webhook'lar, TrustChex hesabınızda gerçekleşen olaylar hakkında uygulamanızın gerçek zamanlı bildirimleri almasını sağlar. Bir olay meydana geldiğinde, yapılandırılmış webhook URL'sine bir HTTP POST isteği gönderiyoruz.

Temel Özellikler:

  • Gerçek zamanlı olay bildirimleri
  • Üstel geri çekilme ile otomatik yeniden deneme mekanizması
  • Güvenlik için HMAC SHA256 imza doğrulama
  • Kapsamlı olay günlüğü ve izleme
  • Kolay hata ayıklama için test işlevselliği

Olay Türleri​

Doğrulama Oturumu Olayları​

  • verification_session.created - Yeni bir doğrulama oturumu oluşturuldu
  • verification_session.completed - Doğrulama oturumu tamamlandı
  • verification_session.cancelled - Doğrulama oturumu iptal edildi

Kimlik Doğrulama Olayları​

  • identification.created - Yeni bir kimlik doğrulama oluşturuldu
  • identification.submitted - Kimlik doğrulama inceleme için gönderildi
  • identification.failed - Kimlik doğrulama işlemi başarısız oldu
  • identification.in_automatic_review - Kimlik doğrulama otomatik inceleme altında
  • identification.in_manual_review - Kimlik doğrulama manuel inceleme gerektiriyor
  • identification.waiting_for_status_change_approval - Durum değişikliği onay bekliyor
  • identification.approved - Kimlik doğrulama onaylandı
  • identification.rejected - Kimlik doğrulama reddedildi
  • identification.resubmission_required - Kimlik doğrulama yeniden gönderim gerektiriyor

Webhook Yönetimi​

Webhook Oluşturma​

  1. Panonuzda Ayarlar > Webhook'lar bölümüne gidin
  2. "Yeni Webhook" butonuna tıklayın
  3. Webhook'unuzu yapılandırın:
    • URL: Webhook olaylarını almak istediğiniz uç nokta
    • Açıklama: Webhook'unuz için isteğe bağlı açıklama
    • Olaylar: Abone olmak istediğiniz olay türlerini seçin
    • Aktif: Webhook'u etkinleştirin/devre dışı bırakın
  4. Webhook'unuzu oluşturmak için "Kaydet" butonuna tıklayın

Webhook'ları Test Etme​

Uç noktanızı doğrulamak için webhook panosundaki test butonunu kullanın:

  1. Webhook'unuzun yanındaki Test butonuna tıklayın
  2. Uç noktanıza bir test olayı gönderilecek
  3. Teslimat durumunu görmek için olay günlüklerini kontrol edin
  4. Hata ayıklama için istek/yanıt ayrıntılarını inceleyin

Webhook Yükü​

Tüm webhook'lar aşağıdaki standart alanları içerir:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "accountId": "hesap-id-niz",
  "webhookId": "webhook-id",
  "eventType": "identification.approved",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "data": {
    "accountId": "hesap-id-niz",
    "identificationId": "kimlik-dogrulama-id",
    "status": "APPROVED",
    "email": "[email protected]",
    "phoneNumber": "+1234567890",
    "score": 95,
    "createdAt": "2024-01-01T11:00:00.000Z",
    "updatedAt": "2024-01-01T12:00:00.000Z"
  }
}

Olaya Özel Yük Örnekleri​

Doğrulama Oturumu Veri Yapısı​

{
  "data": {
    "accountId": "hesap-id-niz",
    "sessionId": "oturum-id",
    "status": "COMPLETED",
    "identificationId": "kimlik-dogrulama-id",
    "email": "[email protected]",
    "phoneNumber": "+1234567890",
    "locale": "tr",
    "sendOTP": true,
    "createdAt": "2024-01-01T11:00:00.000Z",
    "updatedAt": "2024-01-01T12:00:00.000Z",
    "expiresAt": "2024-01-01T13:00:00.000Z"
  }
}

Kimlik Doğrulama Veri Yapısı​

{
  "data": {
    "accountId": "hesap-id-niz",
    "identificationId": "kimlik-dogrulama-id",
    "status": "APPROVED",
    "email": "[email protected]",
    "phoneNumber": "+1234567890",
    "score": 95,
    "createdAt": "2024-01-01T11:00:00.000Z",
    "updatedAt": "2024-01-01T12:00:00.000Z"
  }
}

Başlıklar​

Her webhook isteği şu başlıkları içerir:

  • Content-Type: application/json
  • User-Agent: TrustChex-Webhook/1.0
  • X-Webhook-Event: {eventType}
  • X-Webhook-Delivery: {deliveryId}
  • X-Webhook-Timestamp: {timestamp}
  • X-Webhook-Secret: {secret} (yapılandırılmışsa)
  • X-Webhook-Signature-256: sha256={signature} (gizli anahtar yapılandırılmışsa)

Güvenlik​

Gizli Anahtar Doğrulama​

Webhook'unuz için bir gizli anahtar yapılandırırsanız, bunu X-Webhook-Secret başlığına dahil ederiz ve X-Webhook-Signature-256 başlığında bir HMAC SHA256 imzası oluştururuz.

İmzayı doğrulamak için:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Teslimat ve Yeniden Denemeler​

  • Webhook'ların 30 saniyelik zaman aşımı vardır
  • Başarısız teslimatlar üstel geri çekilme ile en fazla 3 kez yeniden denenir (1s, 3s, 9s)
  • HTTP durum kodları 2xx başarılı olarak kabul edilir
  • Tüm webhook denemeleri günlüğe kaydedilir ve panoda görüntülenebilir

Test Etme​

Uç noktanıza bir test olayı göndermek için webhook panosundaki test işlevselliğini kullanın:

{
  "id": "test-teslimat-id",
  "accountId": "hesap-id-niz",
  "webhookId": "webhook-id-niz",
  "eventType": "test.webhook",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "data": {
    "message": "Bu bir test webhook teslimatıdır",
    "test": true
  }
}

Test Uç Noktası​

Test amaçları için, genel webhook uç noktamızı kullanabilirsiniz:

https://domain-adresiniz.com/api/public/webhooks

Sorgu parametreleri:

  • ?fail=true - Başarısızlığı simüle eder (500 döndürür)
  • ?status=404 - Belirli durum kodu döndürür
  • ?delay=5000 - Milisaniye cinsinden gecikme ekler (maksimum 60000)

En İyi Uygulamalar​

  1. İdempotentlik: Yinelenen olayları işlemekten kaçınmak için webhook teslimat ID'sini kullanın
  2. Zaman Aşımı Yönetimi: Zaman aşımlarını önlemek için 30 saniye içinde yanıt verin
  3. Hata Yönetimi: Uygun HTTP durum kodları döndürün (başarı için 2xx)
  4. Güvenlik: Gizli anahtarlar kullanırken her zaman webhook imzalarını doğrulayın
  5. Günlük Kayıtları: Hata ayıklama ve izleme için webhook olaylarını günlüğe kaydedin
  6. Zarif Bozulma: Uygulamanızda webhook hatalarını zarif bir şekilde yönetin

Örnek Uygulamalar​

Node.js Express​

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature-256'];
  const secret = process.env.WEBHOOK_SECRET;
  
  if (secret && signature) {
    const payload = JSON.stringify(req.body);
    const expectedSignature = 'sha256=' + crypto
      .createHmac('sha256', secret)
      .update(payload)
      .digest('hex');
    
    if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
      return res.status(401).send('Yetkisiz');
    }
  }
  
  console.log('Webhook alındı:', req.body);
  
  // Webhook olayını işle
  switch (req.body.eventType) {
    case 'identification.approved':
      // Onay işlemini yönet
      break;
    case 'identification.rejected':
      // Red işlemini yönet
      break;
    default:
      console.log('Bilinmeyen olay türü:', req.body.eventType);
  }
  
  res.json({ received: true });
});

Python Flask​

import hmac
import hashlib
import json
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Webhook-Signature-256')
    secret = os.environ.get('WEBHOOK_SECRET')
    
    if secret and signature:
        payload = request.get_data()
        expected_signature = 'sha256=' + hmac.new(
            secret.encode('utf-8'),
            payload,
            hashlib.sha256
        ).hexdigest()
        
        if not hmac.compare_digest(signature, expected_signature):
            return jsonify({'error': 'Yetkisiz'}), 401
    
    data = request.get_json()
    print(f"Webhook alındı: {data}")
    
    # Webhook olayını işle
    event_type = data.get('eventType')
    if event_type == 'identification.approved':
        # Onay işlemini yönet
        pass
    elif event_type == 'identification.rejected':
        # Red işlemini yönet
        pass
    
    return jsonify({'received': True})